001 /**
002 * Java Gui Builder - A library to build GUIs using an XML file.
003 * Copyright 2002, 2003 (C) François Beausoleil
004 *
005 * This library is free software; you can redistribute it and/or
006 * modify it under the terms of the GNU Lesser General Public
007 * License as published by the Free Software Foundation; either
008 * version 2.1 of the License, or (at your option) any later version.
009 *
010 * This library is distributed in the hope that it will be useful,
011 * but WITHOUT ANY WARRANTY; without even the implied warranty of
012 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
013 * Lesser General Public License for more details.
014 *
015 * You should have received a copy of the GNU Lesser General Public
016 * License along with this library; if not, write to the Free Software
017 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
018 */
019
020 package jgb.builder;
021
022 import org.xml.sax.ContentHandler;
023 import org.xml.sax.EntityResolver;
024 import org.xml.sax.SAXException;
025 import org.xml.sax.InputSource;
026
027 import javax.swing.*;
028 import java.io.IOException;
029 import java.io.InputStream;
030 import java.io.PrintWriter;
031 import java.awt.*;
032
033 public interface Builder extends ContentHandler, WindowContext {
034 /**
035 * Initiates or terminates quiet mode.
036 * <p>
037 * When in quiet mode, the Builder will not report any messages to the
038 * {@linkplain #setLoggingStream logging stream}. By default, the
039 * Builder is NOT quiet.
040 * </p
041 * <p>
042 * This attribute is mutually exclusive with
043 * {@linkplain #setVerbose verbose}.
044 * </p>
045 * @param quiet <code>true</code> to make the Builder quiet,
046 * <code>false</code> otherwise.
047 */
048 void setQuiet(boolean quiet);
049
050 /**
051 * Makes the Builder more verbose than normal.
052 * <p>
053 * If the Builder is verbose, it should log all start and end elements
054 * to the {@linkplain #setLoggingStream logging stream}.
055 * </p>
056 * <p>
057 * This attribute is mutually exclusive with {@linkplain #setQuiet quiet}.
058 * </p>
059 * @param verbose <code>true</code> to make the Builder verbose,
060 * <code>false</code> otherwise.
061 */
062 void setVerbose(boolean verbose);
063
064 /**
065 * Initiates building of the objects by reading the specified
066 * {@link java.io.InputStream InputStream}.
067 * This stream will be parsed as an XML file. The parser used to parse
068 * the file will be validating.
069 * @throws SAXException If a parser could not be instantiated, or a build
070 * error occurs.
071 * @throws IOException If an I/O error occurs while reading the stream.
072 * @throws IllegalArgumentException If the input stream is
073 * <code>null</code>.
074 */
075 Component build(InputStream in) throws IOException, SAXException;
076
077 /**
078 * Initiates building of the objects by reading the specified
079 * {@link org.xml.sax.InputSource InputSource}.
080 * The parser used to parse the source will be validating.
081 * @throws SAXException If a parser could not be instantiated, or a build
082 * error occurs.
083 * @throws IOException If an I/O error occurs while reading the stream.
084 * @throws IllegalArgumentException If the input source is
085 * <code>null</code>.
086 */
087 Component build(InputSource in) throws IOException, SAXException;
088
089 /**
090 * Specifies the stream to which warnings, errors, fatal errors and
091 * elements should be reported.
092 * @param logStream The stream to which information will be sent.
093 */
094 void setLoggingStream(PrintWriter logStream);
095
096 /**
097 * Adds an {@link org.xml.sax.EntityResolver} through which this Builder
098 * should try to resolve entities before letting the default handling
099 * do it's job.
100 * @param resolver An {@link org.xml.sax.EntityResolver} that will be
101 * used while building the window.
102 */
103 void addResolver(EntityResolver resolver);
104 }